home *** CD-ROM | disk | FTP | other *** search
/ Belgian Amiga Club - ADF Collection / BS1 part 26.zip / BS1 part 26 / Aztec C v5.2a disk 2.adf / reslib52.lzh / readme < prev    next >
Text File  |  1991-10-23  |  9KB  |  196 lines
  1.             Creating and using libraries using Aztec C v5.0
  2.  
  3. 1. Introduction
  4.  
  5.     The structure and use of resident libraries is discussed in the Amiga
  6. Rom Kernel Manuals. In brief, each library has a pointer to a library
  7. structure. Preceding this structure is a jump table with entry points
  8. for each function in the library. When a library is opened, the pointer
  9. to the library structure is returned. When a call is made to the library,
  10. parameters are placed in the appropriate registers, the library pointer
  11. is placed in register A6 and the appropriate negative offset is called.
  12.  
  13.     With previous version of Aztec C, when the user wanted to call a
  14. library routine, an assembly language glue routine would take the
  15. arguments from the stack and place them in the proper registers. It
  16. would then load A6 with the appropriate library base pointer and make
  17. the call restoring any registers used after the call.
  18.  
  19.     The funtions pointed to by the library vector would also be an
  20. assembly language stub that would save registers, set up any registers
  21. needing it, push the register paramters onto the stack and then
  22. call the C language function which would handle the request.
  23.  
  24.     Now, with version 5.0 of Aztec C, the entire procedure is much
  25. simpler and more efficient.
  26.  
  27. 2. Calling Resident Libraries
  28.  
  29.     Making a call to a resident library is very simple with version 5.0
  30. of Aztec C through the use of an "amicall" #pragma statement. (#pragma
  31. statements are the ANSI supported way of doing magic things with the
  32. compiler.) An "amicall" statement takes the form:
  33.  
  34.     #pragma amicall(libBase, offset, func(reg1,reg2,...,regn))
  35.  
  36. In this statement, the "libBase" parameter is the name of the variable
  37. which contains a pointer to the library as returned by OpenLibrary().
  38. "offset" is the POSITIVE offset value for this function. "func" is the
  39. actual name of the function being called. "regX" is the register in
  40. which the particular parameter is to be passed. For example, the
  41. Exec call AllocMem() has a pragma defined as follows:
  42.  
  43.  
  44.     #pragma amicall(SysBase, 0xc6, AllocMem(d0,d1))
  45.  
  46. which declares that SysBase is the variable containing the pointer
  47. to Exec's library base structure. The routine to be called is at
  48. offset -(0xc6) from the SysBase pointer. The name of the routine is
  49. "AllocMem" and the two arguments are to be passed in registers d0 and
  50. d1 respectively.
  51.  
  52.     Now, when the compiler sees a statement like:
  53.  
  54.     ptr = AllocMem(sizeof(struct Node), MEMF_PUBLIC|MEMF_CLEAR);
  55.  
  56. some form of the following code is generated:
  57.  
  58.     move.l    a6,-(sp)
  59.     move.l    #14,d0
  60.     move.l    #$10001,d1
  61.     move.l    _SysBase,a6
  62.     jsr        -$c6(a6)
  63.     move.l    (sp)+,a6
  64.     move.l    d0,_ptr
  65.  
  66. Thus, no assembly language glue is required, since the compiler handles
  67. it all automatically.
  68.  
  69.     For the resident libraries that are a basic part of the amiga computer,
  70. ANSI style prototypes and "amicall" pragmas have been defined in the
  71. file "functions.h" which is found in the standard Aztec C include directory.
  72. Thus, ANY file which contains a reference to an Amiga library call should:
  73.  
  74.     #include <functions.h>
  75.  
  76. Since, there are over 500 amiga functions, precompiling functions.h is
  77. greatly recommended.
  78.  
  79.     So, when you are creating your own resident library, the only thing
  80. you need to do to allow Aztec C programs to make calls to your library
  81. is to define the appropriate "#pragma amicall" statements in a header
  82. file and the compiler will do the rest of the work. (For an example, see
  83. the "mylib.h" header file in this directory.)
  84.  
  85.  
  86. 3. Creating Resident Libraries
  87.  
  88.     Creating resident libraries is now very simple. In this directory,
  89. there are two files called "libstart.asm" and "libsup.c". The first
  90. file contains the assembly language rom tag structure and the assembly
  91. language initialization required for Aztec C's small model. The only
  92. thing that needs to be modified is the version number and priority.
  93. These are defined as two macros called MYVERSION and MYPRI at the
  94. beginning of the file. Three other names, _myname, _myid, and
  95. _myInitTab are referenced, but are defined in the "libsup.c" file.
  96.  
  97.     The "libsup.c" file contains some data structures and four
  98. initialization and support routines. The first data structure is
  99. the "libfunctab" which is a table of pointers to functions which
  100. correspond to the functions which will be pointed to by the vector
  101. table. The first three entries are required to be a library and
  102. contain pointers to three routines found in "libsup.c". The fourth
  103. entry is reserved. All remaining entries are the user defined
  104. routines. In the example code, two functions are shown, "Func1" and
  105. "Func2". Finally, a -1 value indicates the end of the table.
  106. Note that the only thing that needs to be changed here is to change
  107. "Func1" and "Func2" to point to your own routines and to add the
  108. names of any additional routines.
  109.  
  110.     The second structure, "myInitTab", points to the first structure
  111. and to the startup code in "libstart.asm" and need not be changed.
  112.  
  113.     Next, are some data definitions which give the revision level, the
  114. name of the library, and an id string. These should be modified to
  115. reflect the library that you are creating. The names of the variables
  116. (myname, myid) should not be changed unless the "libstart.asm" file
  117. is modified to mirror the changes made.
  118.  
  119.     The first routine, "_main", is called by the startup code when the
  120. library is first loaded into memory and only then. Additional calls
  121. to OpenLibrary will only cause "myOpen" to be called each time.
  122. "myOpen" handles keeping track of the number of times the library has
  123. been opened. "myClose" decrements the open count and if it goes to
  124. zero and somebody asked for an expunge previously, "myExpunge" is
  125. called.
  126.  
  127.     The last routine, "myExpunge", is called when the system requires
  128. more memory. If the open count is zero, the library removes itself
  129. from the library list and frees the memory associated with the library.
  130. If the open count is not yet zero, a flag is set so that the library
  131. will expunge itself when the open count goes to zero. A pointer to
  132. the library segment list is returned if the expunge is successful which
  133. allows the code associated with the library to be removed from memory.
  134.  
  135.     None of these routines need be modified unless some special action
  136. is required when opening, closing or expunging the library.
  137.  
  138.     So, the only things that need be modified in the file, "libsup.c",
  139. are MYREVISION, "myname", "myid" and the names of the user functions
  140. in the "libfunctab".
  141.  
  142.     The only thing left to do is to create the user routines. The example
  143. code shows the two routines "Func1" and "Func2" in the file "lib.c". The
  144. first routine stores the value passed to it. The second routine adds
  145. the value passed to it to the value previously stored and returns the new
  146. value. Note that the only thing special about these routines is the
  147. declaration of an unitialized variable matching the name of the library
  148. base of this library. The compiler will automatically assign this variable
  149. to the register A6 which contains a pointer to the library base when the
  150. routine is called.
  151.  
  152.     The parameters to the function are actually in registers when the
  153. function is called. However, the compiler will automatically deal with
  154. the parameters because of the "amicall" pragma for each function which
  155. is defined in the "mylib.h" file.
  156.  
  157.     And that's all there is to it. The file, "test.c", contains an
  158. example of how the functions would be used. Note that the file,
  159. "mylib.h", is included in "test.c" so that the paramters are passed
  160. in the right registers.
  161.  
  162.  
  163. 4. Miscellaneous Notes
  164.  
  165. - Any function referenced in an amicall or regcall pragma must have been
  166.     previously declared (preferably with a prototype of the arguments).
  167.     For example:
  168.  
  169.         #pragma amicall(mylibBase, 0x1e, Func1(d0))
  170.  
  171.     by itself will generate an error, while:
  172.  
  173.         void Func1(long value);
  174.  
  175.         #pragma amicall(mylibBase, 0x1e, Func1(d0))
  176.  
  177.     is correct.
  178.  
  179. - The other conventions for amiga library pragmas, libcall and syscall,
  180.     are parsed and handled just like amicall.
  181.  
  182. - If the compiler is invoked with small code or data, at the beginning
  183.     of each function which has an accompanying "amicall" pragma, register
  184.     A4 is saved and loaded with the appropriate pointer to the libraries
  185.     data. A4 is restored on exit. If invoked with large code and large
  186.     data, A4 is not affected.
  187.  
  188. - If you wish to make your library be of general use, you should create
  189.     a ".fd" file which specifies the parameter passing conventions and
  190.     function names for your program. Then use the MAPFD program to
  191.     convert the file into a set of #pragmas and a set of assembly
  192.     language glue routines. Include the ".fd" file as well since BASIC
  193.     and other languages may have their own MAPFD type program to get
  194.     access to new libraries. (See the example "mylib.fd" file.)
  195.  
  196.